3D Graphics Programming with QuickDraw 3D 1.5.4

Texture and Bitmap Methods

To write a drawing engine, you need to implement several private methods for managing bitmaps. If your engine supports texture mapping, you also need to implement several private methods for managing textures.

Pointers to your drawing engine's texture and bitmap methods are returned to QuickDraw 3D RAVE by your TQAEngineGetMethod method. See page [link] for details.

TQATextureNew

A drawing engine may define a method to create a new texture map. This method is optional and must be supported only by drawing engines that support texture mapping.



 
typedef TQAError (*TQATextureNew) (

                     unsigned long flags, 

                     TQAImagePixelType pixelType, 

                     const TQAImage images[], 

                     TQATexture **newTexture);

flags: A set of bit flags specifying features of the new texture map. See "Texture Flags Masks" for complete information.
pixelType: The type of pixels in the new texture map. See "Pixel Types" for a description of the values you can pass in this parameter.
images: An array of pixel images to use for the new texture map. The values in the width and height fields of these structures must be an even power of 2.
newTexture: On entry, the address of a pointer variable. On exit, that variable points to a new texture map. If a new texture map cannot be created, *newTexture is set to the value NULL .

DESCRIPTION

Your TQATextureNew function is called whenever an application calls QATextureNew . Your function should perform any tasks required to use the texture in texture-mapping operations. This might involve loading the texture into memory on the device associated with your drawing engine. If so, your TQATextureNew function should not return until the texture has been completely loaded.

The flags parameter specifies a set of texture map features. If the kQATexture_Lock bit in that parameter is set but your drawing engine cannot guarantee that the texture will remain locked in memory, your TQATextureNew function should return an error.

If the kQATexture_Mipmap bit of the flags parameter is clear, the images parameter points to a single pixel image that defines the texture map. If the kQATexture_Mipmap bit is set, the images parameter points to an array of pixel images of varying pixel depths. The first element in the array must be the mipmap page having the highest resolution, with a width and height that are even powers of 2. Each subsequent pixel image in the array should have a width and height that are half those of the previous image (with a minimum width and height of 1).

TQATextureDetach

A drawing engine may define a method to detach a texture map. This method is optional and must be supported only by drawing engines that support texture mapping.



 
typedef TQAError (*TQATextureDetach) (TQATexture *texture);

texture: A texture map.

DESCRIPTION

Your TQATextureDetach function is called whenever an application calls QATextureDetach . Your function should, if necessary, load the texture specified by the texture parameter into memory on the device associated with your drawing engine (so that the caller can release the memory occupied by the texture). Your TQATextureDetach function should not return until the texture has been completely loaded.

TQATextureBindColorTable

A drawing engine may define a method to bind a color lookup table to a texture map.



 
typedef TQAError (*TQATextureBindColorTable) (

                     TQATexture *texture, 

                     TQAColorTable *colorTable);

texture: A texture map.
colorTable: A color lookup table (as returned by a previous call to QAColorTableNew ).

DESCRIPTION

Your TQATextureBindColorTable function is called whenever an application calls QATextureBindColorTable . Your function should bind the color lookup table specified by the colorTable parameter to the texture map specified by the texture parameter. Note that the type of the specified color lookup table must match that of the pixel type of the texture map to which it is bound. For example, a color lookup table of type kQAColorTable_CL8_RGB32 can be bound only to a texture map whose pixel type is kQAPixel_CL8 .

TQATextureDelete

A drawing engine may define a method to delete a texture map. This method is optional and must be supported only by drawing engines that support texture mapping.



 
typedef void (*TQATextureDelete) (TQATexture *texture);

texture: A texture map.

DESCRIPTION

Your TQATextureDelete function is called whenever an application calls QATextureDelete . Your function should delete the texture map specified by the texture parameter.

TQABitmapNew

A drawing engine must define a method to create a new bitmap.



 
typedef TQAError (*TQABitmapNew) (

                     unsigned long flags, 

                     TQAImagePixelType pixelType, 

                     const TQAImage *image, 

                     TQABitmap **newBitmap);

flags: A set of bit flags specifying features of the new bitmap. See "Bitmap Flags Masks" for complete information
pixelType: The type of pixels in the new bitmap. See "Pixel Types" for a description of the values you can pass in this parameter.
image: A pixel image to use for the new bitmap. The width and height fields of this image can have any values greater than 0.
newBitmap: On entry, the address of a pointer variable. On exit, that variable points to a new bitmap. If a new bitmap cannot be created, *newBitmap is set to the value NULL .

DESCRIPTION

Your TQABitmapNew function is called whenever an application calls QABitmapNew . Your function should perform any tasks required to draw the bitmap in the draw context associated with your drawing engine. This might involve loading the bitmap into memory on the device associated with your drawing engine. If so, your TQABitmapNew function should not return until the bitmap has been completely loaded.

The flags parameter specifies a set of bitmap features. If the kQABitmap_Lock bit in that parameter is set but your drawing engine cannot guarantee that the bitmap will remain locked in memory, your TQABitmapNew function should return an error.

TQABitmapDetach

A drawing engine must define a method to detach a bitmap from a drawing engine.



 
typedef TQAError (*TQABitmapDetach) (TQABitmap *bitmap);

bitmap: A bitmap.

DESCRIPTION

Your TQABitmapDetach function is called whenever an application calls QABitmapDetach . Your function should, if necessary, load the bitmap specified by the bitmap parameter into memory on the device associated with your drawing engine (so that the caller can release the memory occupied by the bitmap). Your TQABitmapDetach function should not return until the bitmap has been completely loaded.

TQABitmapBindColorTable

A drawing engine may define a method to bind a color lookup table to a bitmap.



 
typedef TQAError (*TQABitmapBindColorTable) (

                     TQABitmap *bitmap, 

                     TQAColorTable *colorTable);

bitmap: A bitmap.
colorTable: A color lookup table (as returned by a previous call to QAColorTableNew ).

DESCRIPTION

Your TQABitmapBindColorTable function is called whenever an application calls QABitmapBindColorTable . Your function should bind the color lookup table specified by the colorTable parameter to the bitmap specified by the bitmap parameter. Note that the type of the specified color lookup table must match that of the pixel type of the bitmap to which it is bound. For example, a color lookup table of type kQAColorTable_CL8_RGB32 can be bound only to a bitmap whose pixel type is kQAPixel_CL8 .

TQABitmapDelete

A drawing engine must define a method to delete a bitmap.



 
typedef void (*TQABitmapDelete) (TQABitmap *bitmap);

bitmap: A bitmap.

DESCRIPTION

Your TQABitmapDelete function is called whenever an application calls QABitmapDelete . Your function should delete the bitmap specified by the bitmap parameter.